This part is a simple editor designed to be a "starting point" for leaf part development. This part implements a very basic content model (i.e., a pascal string) and implements the majority of OpenDoc features a leaf part might want to provide. This part implements the following features of OpenDoc:
- System Object Model™ (SOM) wrapper / C++ implementation
- lazy display frames handling
- drawing in 4 standard view types
- part persistency
- basic event handling
- multiple display frames/windows
- clipboard operations
- drag and drop
- undo
- translation (with or without Paste As dialog)
- promises (used for interchange)
- handling of part menus
- settings dialog and extension
- dialogs
- zoom rects when opening/closing
- scripting (ODSemantic extension subclass)
- being embedded in a link source or destination
- old file/data type nmap resource
- multiple kind support
Functionality
Cappuccino will display a string of up to 255 bytes in length inside its frame.
In order to change the string that is being displayed, you can use the Set Text dialog box, drop in new text (from any other drag-and-drop-enabled text editing application — for example, SimpleText), or paste new text.
If you click and drag when the Cappuccino part is active, it will initiate a drag operation that includes all of the text that is contained within it.
You may also Cut or Copy the content to the clipboard or Clear it.
A settings dialog is available (either from the menu or from the Part Info dialog box) that allows changing the font and size of the text that is displayed and allows adjusting a flag that indicates whether a frame will be shown at the boundary of the part.
Structure
Cappuccino is designed as a SOM wrapper that dispatches each of its methods to a C++ object which provides the implementation. This C++ object is functionally split into a number of .cpp files.
The main file, Cappuccino.cpp, provides the standard functions that almost all parts must implement. It is based on SamplePart.cpp.
Other files include CappuccinoDragDrop.cpp, CappuccinoClipboard.cpp, CappuccinoUndo.cpp, CappuccinoScripting.cpp, etc. These files implement these additional protocols. Two of these files, CappuccinoLinking.cpp and CappuccinoEmbedding.cpp currently contain mostly "stub" functions for those features that are not implemented in Cappuccino. These functions can be filled in with working code to add support for those features.
In order to handle multiple undo, the content of the part has been factored out into the file CappuccinoContent.cpp, which defines the CCappuccinoContent class and the CSettings class (for settings dialog-type settings). The CappuccinoContent class implements the content model of the part — in the case of Cappuccino a Pascal string. Since this string will be relatively small (from a memory-usage standpoint), an entire string is kept for each undo action state that is maintained.
CCappuccinoContent descends from MRefCounted in order to keep a reference count of the owners of the object. Note that this is not the same as the reference counting SOM class that is part of OpenDoc; it is a C++ mix-in class for doing a simple form of reference counting that deletes the object when the reference count drops to zero. This reference count is used so that a content object can be shared by more than one other object. Currently, a CAction subclass keeps a reference to the current and previous states of the content object for handling undo and redo, a CPromise subclass keeps a reference to the content object whose data it is promising, and the Cappuccino object keeps a reference to the current content of the part.
CCappuccinoContent handles internalizing and externalizing the data of the part, and it also handles multiple kind support and translation for the content.
CappuccinoAction.h/.cpp define and implement the CAction class and subclasses thereof. A CAction is created whenever there is an action being performed that will go onto the Undo stack. In order to use the action, the caller must call the Perform() function after creating a new instance of a CAction subclass. Cappuccino has a subclass for changing the content of the part and another for changing the settings. There is a subclass of CTextChangeAction that handles clipboard-related actions (which have some additional steps required by OpenDoc), and there are several convenience subclasses to implement Set Text, Clear, Drop, etc.
CappuccinoPromise.h/.cpp define and implement the CPromise and CPromiseSet classes. Each CPromise object will keep track of a promise of one kind of content by a single content object. It actually calls the content object to fulfill the promise. A CPromiseSet will keep a list of CPromise objects that all correspond to the same data in different formats. These are used to track the promises that are used for the clipboard and drag-and-drop.
CappuccinoSettingsExt.h/.cpp is a C++ class that implements the methods of a settings extension SOM class. This extension simply calls back into the Cappuccino object when a request is made to display the settings dialog box.
CappuccinoUtils.h/.cpp have a number of utility functions and classes that are used by various files in the project.
TempFocus.h/.cpp contain a utility class for requesting and relinquishing a focus from the OpenDoc arbitrator. This class is in the spirit of the TempObj OpenDoc utility and assures that if an exception is thrown while the part has a particular focus, the focus will be relinquished.
The Print Manager files (Printer.cpp, PrinterQD.cpp, Printer.GX, and Printer.rsrc) are used by the Cappuccino part to do simple printing. You can find this utility documented separately.
Gotchas
• In the Settings dialog box, the font popup menu's dialog item isn't wide enough to include the entire font popup menu.
• Pressing the return key in the Set Text dialog causes the OK button to be selected. This means that returns cannot be entered into the text itself via this dialog.
• When determining if it should accept a drag, Cappuccino does not check the view type of the facet's frame before making its decision about accepting it. This means that a drag will be tracked and accepted even if the frame is in icon or thumbnail view. Generally, this is not the behavior you will want (although it may be useful in certain types of parts), so you should check
in the "if" statement at the beginning of Cappuccino::IsDragSupported() in CappuccinoDragDrop.cpp.
• In its ExternalizeKinds function, Cappuccino will externalize the kinds it is requested to externalize in the order that they are requested. It should externalize them in its own fidelity order. This could be accomplished by creating a list of kinds to externalize and sorting it to conform to the fidelity order defined in CappuccinoContent.cpp.
• The compiler flags (qViewerBuild and qSingleKindSupported) are not fully implemented or tested. The should indicate the sorts of changes that would be need to be made to compile version with those changes, but they are not necessarily full implementations of these features.
• The variable pasteUpdateID in Cappuccino::ContentUpdated() should more appropriately be called updateID.
• If you are creating a part using Cappuccino as a starting point (which is highly recommended), you will probably want to remove the SpeechLib file from the project/makefile unless you intend to support the Speech Manager. There are two places in Cappuccino that use this library. In Cappuccino.cpp in HandleMenuEvent(), there is a call to SpeakString(), and in CappuccinoUtils.cpp, HasSpeech() checks a weak import to see if the Speech Manager is available.
